C/C++ Users Group Library 1996 July/C-C++ Users Group Library July 1996.iso/vol_100/128_01/roff4.doc

Text File | 1985-03-09 | 35KB | 1,058 lines

March 10, 1984
            ROFF4, V1.60

           by Ernest E. Bergmann
           Physics, Building #16
             Lehigh University
            Bethlehem, PA 18015


    ROFF4 is an expanded version of ROFF, based on the
formatter in Kernighan and Plauger's book SOFTWARE TOOLS, is
written in BDS C, and employs the directed i/o functions
that go along with that package.  Well, half of the directed
I/O anyway - it doesn't use redirected input because more
than one file can be used as input for a run.  So that some
of the input files may be used to "set-up" the formatter for
a particular style and for particular hardware.  It is
possible to substitute keyboard input instead of files for
educational and test purposes.

    ROFF was provided by Neal Somos for the public
domain via the BDS 'C' Users' Group's volume, CUG -- "Just
Like Mom's".  Some of this documentation started there as
well.

    This formatter contains features important for the
preparation of technical manuscripts.  Special symbols or
fonts that can be defined by or for the user can be produced
(if the hardware is capable!).  Super and subscripts can be
handled as well as backspace even for printers without
reverse scrolling or backspacing hardware capabilities.
However, the output device should recognize separately the
<CR> and <LF> functions.  The Epson MX-80 with GRAFTRAX 80
was used by the author for most of the development, however
he also was able to use the video display of the Exidy
Sorcerer, which has user definable graphics.  "Preprocessor"
directives can be used to merge stock phrases, boiler plate,
make macro definitions, automate numbering, and create
diversions (for footnotes, table of contents, etc.)

    To support the capabilities of WORDSTAR[tm by
MicroPro] extended underlining, strikeout, and multiple
strike capability are provided as well.

    For more details on the directed I/O see the files,
NDIO.C and DIO.H that are included here for completeness, but
came from CUG--"Just Like Mom's".


Sample calls:(recommended to use console, files (">") and
        list (")") only; printer and robot-typewriter
        are not implemented for my system)

A>roff4 filename1 filename2 filename3 +}

    this would send the formatted version of these three
    files to the console and to the printer


A>roff4 filename1 +}]>filename1

    this would format filename1 and send it to the printer,
    console, robot-typewriter, and back to filename1.

A>roff4 -s -f filename1 -b filename2 -f -m -r -d -i -g -*

    The option, -s, causes the formatter to stop (pause)
    at the start of each page of output; the bell at the
    console is sounded (if it exists!) and the program
    waits until any key is pressed at the console.  It
    is essential for printers that are feed single sheets
    at a time!

    An option that was not shown above, -o[page or range],
    is used to selectively generate output of ONLY certain
    pages.  It is useful to retype pages that got "eaten"
    by the printer (Henry Harpending's aptly put language).
    To retype only page 23, say, make the option: -o23
    To retype pages 23 through 29 use: -o23-29
    To retype pages 23 to the end use: -23-
    These options changes the values of the internal
    variables, FIRSTPAGE and LASTPAGE which originally
    have the values of 1 and 30000, respectively.  Normally
    this option would be placed early enough in the
    command line that no pages have been printed yet.

    The option, -f, would introduce a formfeed (0CH)
    into the output stream (useful for placing blank
    pages, or aligning printer pages) where it appears;
    in this example, before the first page of output,
    and, again, at the very end of the output.

    The option, -b,  turns on the "debug" flag so as to
    print out lots of diagnostics to the STDERR[console].
    Probably only useful for those who are trying to
    trace the operation of the formatter for elusive
    "bugs".

    The option, -m, causes a list of macro definitions
    to be typed to the console.  It is a useful tool for
    debugging complex macro packages where the
    preprocessor's expansions are too subtle for humans.

    The option, -d, causes a list of diversion files to
    be typed to the console.  Its main virtue is to
    remind the user what files are being generated and
    their approximate size.

    The option, -i, causes a list of string insertions
    to be typed to the console.  Useful for macro writers,
    as was the -m, described above.  Also, for noting
    what are the settings of "standard substitutions",
    such as "today's date".

    The option, -r, causes a list of number registers to
    be typed to the console.  Could be useful to find
    the number of footnotes, etc.

    The option, -g, causes a glossary of defined
    translated characters to be printed on the output
    device.  It is useful to check the appearance of
    all special definable characters and to produce
    a "wall chart" of special characters available.

    The default option, -*, (the * could be any
    unassigned option) means keyboard input (buffered
    line-by-line with a prompt with the character used in
    the option, here *).  Typing a control-Z indicates
    an end-of-file; the formatter will continue with the
    next named file.  It is intended as a learning aid
    since one can tryout "tricky" input such as
    equations.  As with standard CP/M, a control-P can
    be used to toggle the printer to display output
    that would normally be sent to the console; also,
    one can edit the keyboard input with the backspace
    key.

    Using ROFF4, you can make nice printouts of a file,
with as little or as much help from the program as you want,
depending on the commands.  There are default values for all
parameters, so if you don't put any commands in at all, your
file will come out with filled, right-justified lines.  The
default line-length is 60 characters; the default page-
length is 66 lines per page.  "Filled lines" means that as
many input words as possible are packed onto a line before
it is printed; "non-filled" lines go through the formatter
w/o rearrangement.  "Right-justified" simply means that
spaces are added between words to make all the right margins
line up nicely.  To set a parameter, use the appropriate
commands below. All commands have the form of a period
followed by two letters. A command line should have nothing
on it but the command and its arguments (if any); any text
would be lost.

    Extra space will separate text sentences.  The sentence
is recognized by a trailing ':',';','!','?', or a '.'.  For
the '.' there is the additional requirement that either two
or more spaces must spaces must follow it, or that it is at the
end of the source line.

        A command argument can be either ABSOLUTE or RELATIVE :

.in    5    sets the indent value to 5 spaces

.in    +5    sets the indent value to the CURRENT value+5

.ls     -1    sets the line spacing to the current value-1


    Also,  all commands have a minimum and maximum value
that will weed out any odd command settings (like setting
the line spacing to zero, for example. It won't let you do
that, but it could be changed if you REALLY have a burning
desire to do so).

    Some commands cause a "break", which is noted in the
table below.  Before such a command goes into effect, the
current line of text is put out, whether it is completely
filled or not. (this is what happens at the end of a
paragraph, for example.)  A line beginning with spaces or a
tab will cause a break, and will be indented by that many
spaces (or tabs) regardless of the indent value at that time
(this is a "temporary indent", which can also be set
explicitly).  An all blank line also causes a break.  If you
find that some lines that are indented strangely, and it's
not obvious WHY, look at which commands are causing a break,
and which aren't. For instance:

.fi
.ti 0
this is a line of text
.in 8
                    <- blank line
more text for the machine to play with


At first glance it seems obvious that the line "this is a
line of text" will be indented zero spaces, but it won't -
it will be indented 8. The indent command does NOT cause a
break (although the .ti does) so it